Summary

Adds a Superserve-backed sandbox provider under agents.extensions.sandbox.superserve, following the existing hosted sandbox extension pattern. The provider is exposed through the optional superserve extra and uses the superserve Python SDK to create, resume, execute in, and clean up sandboxes.

Superserve is a Firecracker-microVM-based sandbox platform with sub-second cold starts and native pause/resume.

Supported features

• SuperserveSandboxClient / SuperserveSandboxClientOptions for creating sandboxes from curated templates (e.g. superserve/base, superserve/python-3.11, superserve/node-22).
• SuperserveSandboxSession / SuperserveSandboxSessionState for serialized run-state resume.
• Command execution through Commands.run, including streaming output via the SDK's SSE callbacks; timeout and transport errors map to ExecTimeoutError / ExecTransportError.
• Workspace read/write through Files.read / Files.write, with WorkspaceReadNotFoundError on missing files and transient-error retries on writes.
• Tar-based persist_workspace / hydrate_workspace via shell tar over exec.
• Native pause-on-exit via pause_on_exit=True, and client.resume(state) that reattaches via AsyncSandbox.connect(sandbox_id), calls sandbox.resume() when the sandbox is paused, polls get_info() until status == active, and falls back to recreating on not_found / failed / unknown statuses.
• Lazy optional exports from agents.extensions.sandbox so users without the extra can still import the package.

Testing

• 27 unit tests in tests/extensions/sandbox/test_superserve.py mirroring the coverage shape of other sandbox providers: lifecycle, exec error translation (timeout / transport / conflict), path-escape rejection, workspace tar round-trip, all four resume status branches (active, paused, resuming, failed, unknown → recreate), sandbox-local user rejection, runtime-helper cache key.
• Updated tests/sandbox/test_compatibility_guards.py with surface, option/state field-order, and round-trip parametrize entries for the new types.
• Updated tests/sandbox/test_client_options.py round-trip parametrize with a SuperserveSandboxClientOptions(template=\"superserve/base\") instance.
• `make lint`, `make format`, `make typecheck`, full sandbox test suite (594 tests) pass locally.
• Live-verified end-to-end against a production Superserve account via examples/sandbox/extensions/superserve_runner.py, in both default (kill-on-exit → recreate → hydrate from local tar) and --pause-on-exit (reattach → sandbox.resume() → poll until active) flows.

Checks

• I've added new tests (if relevant)
• I've added/updated the relevant documentation
• I've run `make lint` and `make format`
• I've made sure tests pass